Building a Shop Platform Integrations

Here are some tips on how to create a new integration and what steps are needed.

These steps assume you have gone through the registring and authorizations steps for a new integration. After that is done you have what you need to authenticate yourself and can continue building a new integration.

Step 1: Adding a shop

The first step in creating a Shop platform integration is creating a shop. This is the object that all your orders and products will be linked to. You can find a deeper explanation about the shop concept here but for now we'll just create the shop by using this endpoint.

Step 2: Adding products

Once we have created a shop we can start adding products to our integration. This is not the same as inventory, rather, we are just adding meta data about the product itself. We'll cover adding inventory in the next step.

Using add product endpoint will get the job done for us. A point worth noting here is, add as much info about the product as you have. The more info we have, the more options you have later using Pio when doing different operations. We also show product images if there is one. So, by adding a URL to a hosted image in image_src we can show this whenever we need to.

Step 3: Adding inventory

This step is not one that can be done via an API endpoint. The inventory level is determined by the amount of products that are stored and picked.

Both of these operations are done using the Pio App itself. There are two types of locations you can store items on in Pio. You can either store it in the grid or if you have any physical shelves, it can be stored there.

For simplicity, you can use the admin user you have and log in to the Sandbox Pio APP.

After logging in you should see something like this

By pressing port in the top left corner you are taken to what we call the port view which should look like the image below.

By pressing the big "Store" button you are ready to start storing some products. Since you most likely won't have a grid connected yet you should see something like this after pressing the button

We have some great guides, one of them are on how to store items on shelf. You can jump over the first step as there is no grid, so have a look here to see how to complete storing items on shelves but jump straight to searching for a product.

When items are stored and inventory increased, Pio will send out a webhook notifying you on this. Containing information about how many are in stock, how many are reserved for orders and how many are available. The exact format of the message can be seen here

Welcome back! Now that you have stored some inventory you can view this by pressing the "Search" button shown in the port view above and searching for the product you just stored. If all went well, you should now see the amount in stock and where it's currently located.

Step 4: Adding orders

The last thing needed to start picking are the order themselves. As with products, including as much information as possible is the best. Notes are displayed to the picker in port and tags on an order can be used to prioritize orders based on rules you can create.

As soon as some orders have been added and there is inventory in stock to fulfil these order, they will appear for picking in the Pio App.

The preparation of new orders happens in a background task, so it might take some time before it appears after the order has been submitted to Pio. When it does get processed, we will send out a webhook message notifying you that a fulfilment has been created for that order. The format of the message can be seen here.

Step 5: Picking an order

Now that you have orders ready, it's time to start picking them. There are several ways to do picking which we won't cover here so for simplicity we will just press the large zest "Pick" button on the port view. This is a simple flow to follow which will result in the products getting reduced from the inventory.

In the same way that we send inventory update messages when storing, we also send out inventory messages when items are picked and inventory reduced because of it. The format of the message is the same as when storing. We will also send out a fulfilment update webhook message to notify you the status of the fulfilment after picking. More specifically in this format